PASI Reference Clients Provincial Approach to Student Information API
Overview

This document provides an introduction to the PASI Reference Client Solution written in Visual Basic .NET and related information for how Software Providers can use the Reference Client as a guide to getting started with PASI integration.

Note: All elements of the Reference Client can be found in the Reference.zip file.

Reference Client Overview

The Reference Client source code is intended to demonstrate the PASI Client system to system interaction with the PASI Core. It provides an example for Software Providers to see how a PASI Client could be coded using VB .NET to integrate with the PASI Core and call the current web services.

The Reference Client VB.NET solution is made up of a number of projects described below:

  • Reference Client Hello World - Is the first reference client that should be viewed. This client demonstrates calling the HelloWorld service in PASI Core allowing confirmation the communication between the client and the core is working correctly and the certificate is registered.
  • Reference Client Student Retrieval - This reference client demonstrates calling the following services: GetStudentPersonalProfile, GetStudentAcademicProfile, IdentifyStudent.
  • Reference Client Student Update - This reference client demonstrates calling the following services: CreateStudent, SubmitStudentProtectionStatus, SubmitStudentPreferredMailingAddress, SubmitStudentAlias, SubmiStudentMailingAddress, SubmitStudentSection23EligibilityStatus, SubmitStudentPhone, SubmitStudentPreferredPhone, SubmitStudentCitizenshipStatus, and SubmitStudentIdentificationInformation.
  • SubmitStudentSchoolEnrolment - This reference client provides an example for calling the SubmitStudentSchoolEnrolment service.
  • Reference Client Entity Synchronization - This reference client demonstrates calling the IsDataAvailable service and its interaction with Get "Entity" services such as: GetStudentSchoolEnrolment, GetSection, GetCourseEnrolment, and GetEvaluatedMark, to keep PASI entities in sync with PASI Core.
  • Reference Client Status Synchronization - This reference client demonstrates calling the IsDataAvailable service and its interaction with Get "Status" services such as: GetStudentSchoolEnrolmentStatus, GetSectionStatus, GetCourseEnrolmentStatus, and GetEvaluatedMarkStatus, to keep both PASI entities and statuses in sync with PASI Core.

For more info about these services please refer to the API Service documentation.

Reference Client Technology Platform

The Reference Client is created using:

  • .NET Framework 4.6 (Visual Basic)
  • Windows 8.1
  • Visual Studio 2015

For non .NET environment Software Providers, the Express Edition can be downloaded free from https://www.microsoft.com/exPress/download/ to access and view the Reference Source Code.

How to run the Reference Client in .NET Environment

The following is a step by step guide on how to configure and run the Reference Client in the MS .NET environment.

Environment Requirements

The following is required in order to run the Reference Client:

  • Microsoft .NET framework 4.6
  • Visual Studio 2015
Project and Solution Setup

Unzip the Reference zip file and open the solution using Visual Studio.

Request or Register for Certificate

The PASI Client Certificate Registration Guide provides direction on how to register to participate in PASI and acquire and/or register a digital certificate with PASI. These activities must take place in order to execute the Reference Client. The PASI Client Certificate Registration Guide is available in the help section of the Certificate Registration Site (https://extranet.education.alberta.ca/Ae.CertificateRequest/).

Security and Service Configurations

Once a digital certificate has been acquired and registered with PASI, it must be stored on the same computer you intend to run the Reference Client. Once a certificate is stored, modify the Reference Client to include the digital certificate. Here are two approaches that can be taken:

Option 1: Use the Certificate Serial Number (recommended)

1) Locate the serial number for the certificate you will use

2) Update the app.config in each reference client project setting "DefaultCertificateSerialNumber"

<setting name="DefaultCertificateSerialNumber" serializeAs="String">

<value>SERIAL NUMBER HERE</value>

</setting>

Option 2: Modify the Supplied Reference Client Sample to Use a pfx File

1) Export your certificate with the private key as a .pfx file and save this file to the application directory.

2) Update the app.config in each reference client project with the file name of your exported certificate and the password.

<setting name="DefaultCertificateFileName" serializeAs="String">

<value>./CertificateFileName.pfx</value>

</setting>

<setting name="DefaultCertificateFilePassword" serializeAs="String">

<value>pfx file Password here</value>

</setting>


3) Change the reference client source code. Open the PASIService class and change the constructor from:

Public Sub New()

Me.New(CertificateManager.GetCertificateBySerialNumber())

End Sub

To

Public Sub New()

Me.New(CertificateManager.GetCertificateFromFile())

End Sub

The last step is to set the OrganizationCode in the app.config to a value that your PASI client can represent (S.0982 is School Code 0982. This should be replaced with a value valid for your client. See the PASI Technical Concepts and Specifications document for more details):

<setting name="OrganizationCode" serializeAs="String">

<value>S.0982</value>

</setting>

Compile and Run

Now that the certificate has been configured right click the reference client project you wish to run and select "Set as StartUp Project". Once the application is running follow the instructions on the screen for any actions you might be able to perform.

Reference Client: Hello World

The Hello World reference client is the most basic. This client will allow you to verify you have conifugred your PASI client certificate correctly.

After entering "PASI Client" press enter. You should see a response like the following:

Reference Client: Student Retrieval

The Student Retrieval Reference Client provides you with sample code to call PASI service operations which are related to retrieving student data. The following service operations are demonstrated:

  1. IdentifyStudent
  2. GetStudentPersonalProfile
  3. GetStudentAcademicProfile
Reference Client: Student Update

The Student Update Reference Client provides you with sample code to call PASI service operations which are related to updating student data. The following service operations are demonstrated:

  1. SubmitStudentProtectionStatus
  2. SubmitStudentPreferredMailingAddress
  3. SubmitStudentAlias
  4. SubmitStudentMailingAddress
  5. SubmitStudentSection23EligibilityStatus
  6. SubmitStudentPhone
  7. SubmitStudentPreferredPhone
  8. SubmitStudentCitizenshipStatus
  9. CreateStudent
  10. SubmitStudentIdentificationInformation

The client presents a menu and the on screen instructions will prompt for some of the required input for each service.

Reference Client: Submit Student School Enrolment

To submit an enrolment run the SubmitStudentSchoolEnrolment reference client. The client accepts some reasonable defaults for certain properties on the request. To accept a default press enter at the relevant prompt.

To update an enrolment specify a valid enrolment reference Id otherwise for new enrolments it will auto generate guids.

Reference Client: Entity Synchronization

The Entity Synchronization reference client's purpose is to demonstrate how to use the IsDataAvailable service to keep a client's entity data in sync with the PASI Core in a near real-time manner for 201204 WCF service endpoint. The client will keep the following entity types in sync with the PASI Core:

  1. School
  2. School Calendar
  3. Section
  4. Student School Enrolment
  5. Course Enrolment
  6. Evaluated Mark

The purpose of this reference client like all reference clients is to demonstrate how to call the PASI Core services. Since calling of the service is the primary focus there was no optimization done to minimize the memory usage of the data structures being stored in the local cache. The algorithm this reference client uses to synchronize should be appropriate for a large school authority but this reference client in its current form may not be able to handle all the data retrieved for a very large school authority.

Remark

This Reference client only handles entity data. Please refer to Reference Client: Status Synchronization for both entity and status data.

IsDataAvailable Events Tab

The "IsDataAvailable Events" tab shows the time and details of the call to IsDataAvailable service before and after. It may also say something like "Synchronized (UpdateAvailable): Section.2010(83)". This means during the call to IsDataAvailable there were 83 sections identified as newer than the version number passed in for the 2010 school year. Since the reference client does not maintain any state (no local database) it brings down all the data it has access to when starting up. The most recent activity is at the top of the list.

The Copy button will copy the selected line from the list to the clipboard.

The Clear button will clear the list of all events.

Local Cache Details Tab

This tab shows some information on the current amount of data in the cache.

School Tab

The "School" tab is used to demonstrate how School entitiesare synchronized with PASI and displayed to the end user.

"Add a Dummy to Cache" button will add a dummy School entity to the local cache.

"Delete Selected from Cache" button will delete the current selected School entity from the local cache.

If either button is clicked, as a result of differences between local cache and PASI Core, an "Resync Required" is generated from the next IsDataAvailable call, and this tab is refreshed to be in sync with PASI Core again.

School Calendar Tab

The "School Calendar" tab is used to demonstrate how School Calendar entitiesare synchronized with PASI and displayed to the end user.

"Add a Dummy to Cache" button will add a dummy School Calendar entity to the local cache.

"Delete Selected from Cache" button will delete the current selected School Calendar entity from the local cache.

If either button is clicked, as a result of differences between local cache and PASI Core, an "Resync Required" is generated from the next IsDataAvailable call, and this tab is refreshed to be in sync with PASI Core again.

Section Tab

The "Section" tab is used to demonstrate how Section entitiesare synchronized with PASI and displayed to the end user.

"Add a Dummy to Cache" button will add a dummy Section entity to the local cache.

"Delete Selected from Cache" button will delete the current selected Section entity from the local cache.

If either button is clicked, as a result of differences between local cache and PASI Core, an "Resync Required" is generated from the next IsDataAvailable call, and this tab is refreshed to be in sync with PASI Core again.

Student School Enrolment Tab

The "Student School Enrolment" tab is used to demonstrate how Student School Enrolment entitiesare synchronized with PASI and displayed to the end user.

"Add a Dummy to Cache" button will add a dummy Student School Enrolment entity to the local cache.

"Delete Selected from Cache" button will delete the current selected Student School Enrolment entity from the local cache.

If either button is clicked, as a result of differences between local cache and PASI Core, an "Resync Required" is generated from the next IsDataAvailable call, and this tab is refreshed to be in sync with PASI Core again.

Course Enrolment Tab

The "Course Enrolment" tab is used to demonstrate how Course Enrolment entitiesare synchronized with PASI and displayed to the end user.

"Add a Dummy to Cache" button will add a dummy Course Enrolment entity to the local cache.

"Delete Selected from Cache" button will delete the current selected Course Enrolment entity from the local cache.

If either button is clicked, as a result of differences between local cache and PASI Core, an "Resync Required" is generated from the next IsDataAvailable call, and this tab is refreshed to be in sync with PASI Core again.

Evaluated Mark Tab

The "Evaluated Mark" tab is used to demonstrate how Evaluated Mark entitiesare synchronized with PASI and displayed to the end user.

"Add a Dummy to Cache" button will add a dummy Evaluated Mark entity to the local cache.

"Delete Selected from Cache" button will delete the current selected Evaluated Mark entity from the local cache.

If either button is clicked, as a result of differences between local cache and PASI Core, an "Resync Required" is generated from the next IsDataAvailable call, and this tab is refreshed to be in sync with PASI Core again.

Reference Client: Status Synchronization

The Status Synchronization reference client's purpose is to demonstrate how to use the IsDataAvailable service to keep a client's status and entity data in sync with the PASI Core in a near real-time manner for 201204 WCF service endpoint. The client will keep the following status types in sync with the PASI Core:

  1. Student School Enrolment Status
  2. Section Status
  3. Course Enrolment Status
  4. Evaluated Mark Status

The purpose of this reference client like all reference clients is to demonstrate how to call the PASI Core services. Since calling of the service is the primary focus there was no optimization done to minimize the memory usage of the data structures being stored in the local cache. The algorithm this reference client uses to synchronize should be appropriate for a large school authority but this reference client in its current form may not be able to handle all the data retrieved for a very large school authority.

Due to the fact that EntityInfo object is a composition of StatusInfo object (eg. SectionStatusInfo.SourceSection), this reference client only calls Get "Status" Service to retrieve both status and entity data.

Remark

This Reference client handles both status and entity data. Please refer to Reference Client: Entity Synchronization for only entity data.

IsDataAvailable Events Tab

The "IsDataAvailable Events" tab shows the time and details of the call to IsDataAvailable service before and after. It may also say something like "Synchronized (UpdateAvailable): Section.2010(83)". This means during the call to IsDataAvailable there were 83 section statuses identified as newer than the version number passed in for the 2010 school year. Since the reference client does not maintain any state (no local database) it brings down all the data it has access to when starting up. The most recent activity is at the top of the list.

The Copy button will copy the selected line from the list to the clipboard.

The Clear button will clear the list of all events.

Local Cache Details Tab

This tab shows some information on the current amount of data in the cache.

Section Status Tab

The "Section Status" tab is used to demonstrate how Section entities and their statuses are synchronized with PASI and displayed to the end user.

"Add a Dummy to Cache" button will add a dummy Section status to the local cache.

"Delete Selected from Cache" button will delete the current selected Section status from the local cache.

If either button is clicked, as a result of differences between local cache and PASI Core, an "Resync Required" is generated from the next IsDataAvailable call, and this tab is refreshed to be in sync with PASI Core again.

"Alerts Detail" button will open the "Status Details" Form for current selected Section Status.

Student School Enrolment Status Tab

The "Student School Enrolment Status" tab is used to demonstrate how Student School Enrolment entities and their statuses are synchronized with PASI and displayed to the end user.

"Add a Dummy to Cache" button will add a dummy Student School Enrolment status to the local cache.

"Delete Selected from Cache" button will delete the current selected Student School Enrolment status from the local cache.

If either button is clicked, as a result of differences between local cache and PASI Core, an "Resync Required" is generated from the next IsDataAvailable call, and this tab is refreshed to be in sync with PASI Core again.

"Alerts Detail" button will open the "Status Details" Form for current selected Student School Enrolment Status.

Course Enrolment Status Tab

The "Course Enrolment Status" tab is used to demonstrate how Course Enrolment entities and their statuses are synchronized with PASI and displayed to the end user.

"Add a Dummy to Cache" button will add a dummy Course Enrolment status to the local cache.

"Delete Selected from Cache" button will delete the current selected Course Enrolment status from the local cache.

If either button is clicked, as a result of differences between local cache and PASI Core, an "Resync Required" is generated from the next IsDataAvailable call, and this tab is refreshed to be in sync with PASI Core again.

"Alerts Detail" button will open the "Status Details" Form for current selected Course Enrolment Status.

Evaluated Mark Status Tab

The "Evaluated Mark Status" tab is used to demonstrate how Evaluated Mark entities and their statuses are synchronized with PASI and displayed to the end user.

"Add a Dummy to Cache" button will add a dummy Evaluated Mark status to the local cache.

"Delete Selected from Cache" button will delete the current selected Evaluated Mark status from the local cache.

If either button is clicked, as a result of differences between local cache and PASI Core, an "Resync Required" is generated from the next IsDataAvailable call, and this tab is refreshed to be in sync with PASI Core again.

"Alerts Detail" button will open the "Status Details" Form for current selected Evaluated Mark Status.

Status Details Form

Showing the details of a status object.